/// Observable field classes for reactive programming.
/// 响应式编程的可观察字段类
///
/// Provides nullable-enabled observable fields based on [ValueNotifier]
/// with additional features like single listener mode and forced notifications.
/// 提供基于 [ValueNotifier] 的可空值可观察字段，具有单监听器模式和强制通知等附加功能。
///
/// Author: sunlunchang
library;

import 'package:flutter/cupertino.dart';
import 'package:flutter/foundation.dart';

/// Read-only observable field.
/// 只读可观察字段
///
/// Extends [ChangeNotifier] to provide observable functionality with nullable values.
/// Unlike [ValueNotifier], this class allows null values.
/// 扩展 [ChangeNotifier] 以提供可空值的可观察功能。
/// 与 [ValueNotifier] 不同，此类允许 null 值。
///
/// Type parameter [T] can be nullable.
/// 类型参数 [T] 可以为空。
class ReadObservableField<T> extends ChangeNotifier implements Listenable {
  /// Whether to allow only a single listener / 是否只允许单个监听器
  final bool single;

  /// The current value (can be null) / 当前值（可以为 null）
  T? _value;

  /// Creates a read-only observable field.
  /// 创建只读可观察字段
  ///
  /// [single] If true, only one listener can be registered at a time (default: false).
  /// [single] 如果为 true，则一次只能注册一个监听器（默认：false）。
  ReadObservableField({this.single = false});

  /// Gets the current value.
  /// 获取当前值
  T? get value => _value;

  /// Adds a listener.
  /// 添加监听器
  ///
  /// If [single] is true and a listener already exists, the new listener
  /// will not be added.
  /// 如果 [single] 为 true 且已存在监听器，则不会添加新的监听器。
  @override
  void addListener(VoidCallback listener) {
    if (hasListeners && single) {
      return;
    }
    super.addListener(listener);
  }

  /// Notifies all registered listeners.
  /// 通知所有已注册的监听器
  @override
  void notifyListeners() {
    super.notifyListeners();
  }
}

/// Mutable observable field.
/// 可变可观察字段
///
/// Extends [ReadObservableField] to provide value setting functionality.
/// Supports nullable values and can notify listeners when value changes.
/// 扩展 [ReadObservableField] 以提供值设置功能。
/// 支持可空值，并在值更改时通知监听器。
///
/// Type parameter [T] can be nullable.
/// 类型参数 [T] 可以为空。
///
/// Example / 示例:
/// ```dart
/// final name = ObservableField<String>(value: 'Alice');
/// name.addListener(() => print('Name changed to ${name.value}'));
/// name.setValue('Bob'); // Prints: Name changed to Bob / 输出：Name changed to Bob
/// ```
class ObservableField<T> extends ReadObservableField<T> {
  /// Creates a mutable observable field.
  /// 创建可变可观察字段
  ///
  /// [value] Initial value (can be null) / 初始值（可以为 null）
  /// [single] If true, only one listener can be registered at a time / 如果为 true，则一次只能注册一个监听器
  ObservableField({T? value, super.single}) {
    _value = value;
  }

  /// Sets a new value.
  /// 设置新值
  ///
  /// [newValue] The new value to set / 要设置的新值
  ///
  /// If the new value equals the current value, no notification occurs.
  /// Otherwise, the value is updated and all listeners are notified.
  /// 如果新值等于当前值，则不会发生通知。
  /// 否则，值将被更新并通知所有监听器。
  void setValue(T? newValue) {
    if (_value == newValue) return;
    _value = newValue;
    notifyListeners();
  }

  /// Sets value and forces notification even if value hasn't changed.
  /// 设置值并强制通知，即使值未更改
  ///
  /// [value] The value to set / 要设置的值
  ///
  /// This is useful when you need to notify listeners even if the value
  /// hasn't actually changed (e.g., to trigger a rebuild).
  /// 当您需要通知监听器即使值实际上没有更改时（例如，触发重建），这很有用。
  void setValueForcedNotify(T? value) {
    if (this.value == value) {
      notifyListeners();
    } else {
      setValue(value);
    }
  }
}

/// Observable integer field.
/// 可观察整数字段
///
/// A specialized [ValueNotifier] for integer values.
/// 用于整数值的专用 [ValueNotifier]。
///
/// Example / 示例:
/// ```dart
/// final counter = ObservableInt(value: 0);
/// counter.addListener(() => print('Counter: ${counter.value}'));
/// counter.value++; // Prints: Counter: 1 / 输出：Counter: 1
/// ```
class ObservableInt extends ValueNotifier<int> {
  /// Creates an observable integer field.
  /// 创建可观察整数字段
  ///
  /// [value] Initial value (default: 0) / 初始值（默认：0）
  ObservableInt({int value = 0}) : super(value);
}

/// Observable double field.
/// 可观察浮点数字段
///
/// A specialized [ValueNotifier] for double values.
/// 用于浮点数值的专用 [ValueNotifier]。
///
/// Example / 示例:
/// ```dart
/// final price = ObservableDouble(value: 9.99);
/// price.addListener(() => print('Price: ${price.value}'));
/// price.value = 19.99; // Prints: Price: 19.99 / 输出：Price: 19.99
/// ```
class ObservableDouble extends ValueNotifier<double> {
  /// Creates an observable double field.
  /// 创建可观察浮点数字段
  ///
  /// [value] Initial value (default: 0.0) / 初始值（默认：0.0）
  ObservableDouble({double value = 0}) : super(value);
}

/// Observable boolean field.
/// 可观察布尔字段
///
/// A specialized [ValueNotifier] for boolean values.
/// 用于布尔值的专用 [ValueNotifier]。
///
/// Example / 示例:
/// ```dart
/// final isEnabled = ObservableBool(value: true);
/// isEnabled.addListener(() => print('Enabled: ${isEnabled.value}'));
/// isEnabled.value = false; // Prints: Enabled: false / 输出：Enabled: false
/// ```
class ObservableBool extends ValueNotifier<bool> {
  /// Creates an observable boolean field.
  /// 创建可观察布尔字段
  ///
  /// [value] Initial value (default: false) / 初始值（默认：false）
  ObservableBool({bool value = false}) : super(value);
}
